home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / patches / hsmoda07 / hsm_doku / sersofst.txt < prev   
Text File  |  1995-09-07  |  36KB  |  803 lines
  1. Festlegung einer Softwareschnittstelle, die eine vollst„ndig
  2. hardwareunabh„ngige Nutzung serieller Interfaces erm”glicht
  3. ============================================================
  4.  
  5. Definition of a software interface, providing a fully hardware
  6. independend use of serial interfaces
  7. ==============================================================
  8. This file contains the english version too, begin to search at the 
  9. middle of the text.
  10.  
  11.  
  12. Text von: Harun Scheutzow, Dresdener Straže 83, D-10179 Berlin
  13. Internet-Email: Harun_Scheutzow@B.maus.de
  14. letzte Žnderung der Definition: 12.11.1993
  15. letzte Žnderung der Erkl„rungen: 14.07.1995
  16.  
  17. Es sollen m”glichst alle Funktionen definiert werden, die ein 
  18. Terminalprogramm, ein šbertragungsprotokoll oder z.B. ein Faxprogramm 
  19. ben”tigt. Diese Funktionen sollen ein hardwareunabh„ngiges Interface fr 
  20. Programme darstellen.
  21.  
  22. Dieser Vorschlag ist Eric Smith bekannt. Es ist (noch?) KEIN 
  23. offizieller Atari-Standard. Eric findet den Vorschlag gut (nur die 
  24. Callbacks h„lt er bezglich Memory Protection fr nicht so toll) und 
  25. meint: Es ist besser, einen inoffiziellen Standard zu haben, als gar 
  26. keinen. Originalton im englischen Teil.
  27.  
  28. MiNT oder TOS oder ein nachzuladender Treiber sollen m”glichst viele der 
  29. hier beschriebenen Funktionen untersttzen, soweit es die Hardware zul„žt. 
  30. Es muž aber jede Soft damit rechnen, daž eine Funktion nicht existiert 
  31. (Rckmeldung EINVFN, -32). Verhindert dies die Arbeit der Soft, so muž der 
  32. Nutzer darber informiert werden.
  33.  
  34. Dies hier ist ein Standardisierungsversuch fr das Interface, das 
  35. Nutzerprogramme vorfinden. šber die Interna der Treiberimplementation soll 
  36. nichts geschrieben werden. Bei allen Funktionen und Vorschl„gen muž aber 
  37. daran gedacht werden, daž diese auch auf einem 68000 mit 8MHz bei 38400Bd 
  38. ber den MFP (also ohne FIFO) realisierbar sind. Die steigende Leistung der 
  39. CPUs ist kein Argument, da die gewnschte Datentransferrate auch st„ndig 
  40. steigt.
  41.  
  42.  
  43. Fopen, Fread, Fwrite, Fclose drften als normale GEMDOS-Funktionen jedem 
  44. bekannt sein. Fcntl ist die im MiNT (und in HSMODEM) vorhandene 
  45. GEMDOS-Funktion $104, mit LONG Fcntl( WORD filehandle, void * special, 
  46. WORD subfunction). Fcntl liefert meist eine 0 als OK-Meldung, oder sonst 
  47. einen Fehlercode. "filehandle" ist das GEMDOS-Filehandle, wie es auch fr 
  48. Fread und Fwrite benutzt wird. "subfunction" ist ein 16-Bit-Wert, der die 
  49. auszufhrende Funktion angibt. "special" ist ein Zeiger auf eine 
  50. Speicherstelle, deren Datentyp (WORD, LONG, irgendeine Struktur) bei den 
  51. einzelnen Unterfunktionen angegeben ist. Auf dieser Speicherstelle 
  52. erwartet Fcntl seine Eingabeparameter. Eventuelle Rckgabeparameter werden 
  53. ebenfalls auf dieser Speicherstelle hinterlassen.
  54.  
  55. Die Reservierung einer Schnittstelle will ich ber den ™ffnungsmodus von Fopen 
  56. realisieren.
  57.  
  58.  
  59.  
  60. Hier ein Versuch der Dokumentation, was MiNT bereits bieten soll. 
  61. Allerdings sind in MiNT nicht alle Funktionen vorhanden oder funktionieren 
  62. nicht ganz, wie sie sollten. 
  63.  
  64.  
  65. Manche Zeilen sind C, manche Kommentar. Bei den angegebenen 
  66. Funktionsaufrufen handelt es sich wirklich um Musteraufrufe, und nicht etwa 
  67. um mižgestaltete Prototypen.
  68.  
  69.  
  70.  
  71. Ermittlung, wieviel Byte nichtblockierend bertragen werden k”nnen
  72. ------------------------------------------------------------------
  73. #define FIONREAD  (('F'<< 8) | 1)
  74. #define FIONWRITE (('F'<< 8) | 2)
  75. Fcntl( handle, &count, FIONREAD)
  76. Fcntl( handle, &count, FIONWRITE)
  77. In count wird als 32Bit-Wert die Anzahl der Byte hinterlassen, die beim 
  78. n„chsten Fread/Fwrite mindestens gelesen/geschrieben werden k”nnen. Da 
  79. aber m”glicherweise mehrere Programme auf einen Port schreiben k”nnten, 
  80. sollte man nur den Returnwert von Fread/Fwrite fr voll nehmen.
  81.  
  82.  
  83. Setzen und Rcksetzen von Break
  84. -------------------------------
  85. #define TIOCCBRK (('T'<< 8) | 20)
  86. #define TIOCSBRK (('T'<< 8) | 21)
  87. Fcntl( handle, dummy, TIOCSBRK); /* Break aktivieren */
  88. Fcntl( handle, dummy, TIOCCBRK); /* Break l”schen */
  89. Fr "dummy" kann irgendein Zeiger eingesetzt werden, da es nicht 
  90. ausgewertet wird.
  91.  
  92.  
  93. Setzen/Abfragen der Eingabegeschwindigkeit und Steuerung der DTR-Leitung
  94. ------------------------------------------------------------------------
  95. #define TIOCIBAUD (('T'<< 8) | 18)
  96. Fcntl( handle, &speed, TIOCIBAUD);
  97. Setze die Eingabegeschwindigkeit der Schnittstelle. In speed steht ein 
  98. 32Bit-Wert, der die gewnschte Geschwindigkeit unkodiert in Bit pro Sekunde 
  99. angibt. speed = 19200 wrde auf 19200bps setzen. In speed wird die 
  100. Geschwindigkeit vor dem Aufruf von TIOCIBAUD zurckgegeben. Ist sie 
  101. unbekannt, wird -1 geliefert. Ist beim Aufruf speed = -1, so wird nur die 
  102. Geschwindigkeit erfragt. Ist speed = 0, so wird das DTR-Signal auf inaktiv 
  103. gebracht (gel”scht), ohne die Geschwindigkeit zu beeinflussen. Bei 
  104. geschwindigkeitssetzendem Aufruf wird DTR automatisch aktiviert. 
  105. Rckgabewert ist ERANGE wenn die Geschwindigkeit nicht einstellbar ist. 
  106. Dann wird als "Ausnahme" in speed die n„chstniedrigere m”gliche 
  107. Geschwindigkeit geliefert. Gibt es keine n„chstniedrige, so wird die 
  108. kleinstm”gliche zurckgegeben.
  109.  
  110.  
  111. Setzen/Abfragen der Ausgabegeschwindigkeit und Steuerung der DTR-Leitung 
  112. ------------------------------------------------------------------------
  113. #define TIOCOBAUD (('T'<< 8) | 19) Fcntl( handle, &speed, TIOCOBAUD);
  114. Setze die Ausgabegeschwindigkeit der Schnittstelle. Die 
  115. Funktionsbeschreibung ist identisch zu TIOCIBAUD. Untersttzt eine 
  116. Schnittstelle getrennte Ein- und Ausgabegeschwindigkeit nicht, so 
  117. beeinflužt jeder Aufruf beide Geschwindigkeiten.
  118.  
  119.  
  120. šbertragungsprotokolleinstellungen erfragen
  121. -------------------------------------------
  122. #define TIOCGFLAGS (('T'<< 8) | 22)
  123. Fcntl( handle, &flags, TIOCGFLAGS);
  124. Liefert in flags einen 16Bit-Wert der eingestellten Parameter, die eine 
  125. ODER-Verknpfung der folgenden Werte darstellen. Alle anderen Bit sind 
  126. reserviert. Bei TIOCGFLAGS sollte man sie ignorieren. Sinnvollerweise 
  127. erfragt man mit TIOCGFLAGS, modifiziert die bekannten Werte, und setzt dann 
  128. per TIOCSFLAGS.
  129.  
  130. /* Anzahl der Stoppbits */
  131. #define TF_STOPBITS 0x0003
  132. /* 0x0000  nicht erlaubt
  133. ERWEITERUNGSVORSCHLAG: So wird der Synchronmode aktiviert. Die restlichen 
  134. Parameter erhalten im Synchronmode andere Bedeutungen. Diese sind sp„ter 
  135. noch festzulegen. */
  136. #define TF_1STOP   0x0001 /* 1 Stoppbit */
  137. #define TF_15STOP  0x0002 /* 1.5 Stoppbit */
  138. #define    TF_2STOP   0x0003 /* 2 Stoppbit */
  139.  
  140. /* Anzahl der Bits pro Zeichen */
  141. #define TF_CHARBITS 0x000C
  142. #define TF_8BIT    0x0 /* 8 Bit */
  143. #define TF_7BIT    0x4
  144. #define TF_6BIT    0x8
  145. #define TF_5BIT    0xC /* 5 Bit */
  146.  
  147. /* Handshakemodi und Parit„t */
  148. #define TF_FLAG  0xF000
  149. #define T_TANDEM 0x1000 /* XON/XOFF (=^Q/^S) Flužkontrolle aktiv */
  150. #define T_RTSCTS 0x2000 /* RTS/CTS Flužkontrolle aktiv */
  151. #define T_EVENP  0x4000 /* even (gerade) Parit„t aktiv */
  152. #define T_ODDP   0x8000 /* odd (ungerade) Parit„t aktiv */
  153. /* even und odd schliežen sich gegenseitig aus */
  154.  
  155.  
  156. šbertragungsprotokolleinstellungen setzen
  157. -----------------------------------------
  158. #define TIOCSFLAGS (('T'<< 8) | 23)
  159. Fcntl( handle, &flags, TIOCSFLAGS);
  160. Setzt die Einstellungen, Beschreibung dieser bei TIOCGFLAGS. Rckgabewert 
  161. ist ERANGE bei illegaler oder nicht untersttzer Kombination in flags.
  162.  
  163.  
  164. Hier endet die Dokumentation der mir bekannten und verst„ndlichen 
  165. Funktionen in MiNT. Es folgen die neuen Vorschl„ge.
  166.  
  167.  
  168. Leeren der seriellen Puffer
  169. ---------------------------
  170. #define TIOCFLUSH (('T'<< 8) | 8)
  171. Fcntl( handle, special, TIOCFLUSH);
  172. (ist doch im Mint "/* BUG: this should flush the input/output buffers */")
  173. Ausw„hlbar ber den special-Parameter werden die seriellen Puffer 
  174. unterschiedlich geleert:
  175. special  Funktion
  176. 0
  177.          Der Sendepuffer soll komplett gesendet werden. Die Funktion kehrt 
  178.          erst zurck, wenn der Puffer leer ist (return E_OK, =0) oder ein 
  179.          systeminterner Timeout abgelaufen ist (return EDRVNR, =-2). Der 
  180.          Timeout wird vom System sinnvoll bestimmt.
  181. 1
  182.          Der Empfangspuffer wird gel”scht.
  183. 2
  184.          Der Sendepuffer wird gel”scht.
  185. 3
  186.          Empfangspuffer und Sendepuffer werden gel”scht.
  187. -tout
  188.          Ein negativer Parameter funktioniert wie 0, aber tout (man 
  189.          beachte, tout selbst ist positiv) gibt den Timeout in 1/200 
  190.          Sekunden vor.
  191.  
  192. Hier gibt es inzwischen eine Inkompatibilit„t zwischen MiNT und den 
  193. HSMODA-Treibern. In neueren MiNT-Versionen sind die Modi 0 bis 3 
  194. realisiert und special ist ein Zeiger auf ein WORD (16 Bit), in dem der 
  195. Modus steht. Bei den HSMODA-Treibern ist special jedoch kein Zeiger, 
  196. sondern der Modus-Wert selbst!
  197.  
  198.  
  199. Stoppen des Empfangs
  200. --------------------
  201. #define TIOCSTOP (('T'<< 8) | 9)
  202. Ist nur in den Handshakemodi verfgbar und teilt dem Kommunikationspartner 
  203. mit, daž der Rechner nichts empfangen m”chte. Die Funktion wartet eine 
  204. sinnvolle Zeitspanne, um in der šbertragung befindliche Zeichen 
  205. einzusammeln. Dann geht sie davon aus, daž der Partner schweigt und kehrt 
  206. zurck. (Anwendungsbeispiel: Ein 8MHz-ST kann nicht gleichzeitig DMA und 
  207. 57600Bd-Empfang ber den MFP.)
  208.  
  209.  
  210. Starten des Empfangs
  211. --------------------
  212. #define TIOCSTART (('T'<< 8) | 10)
  213. Hebt die Wirkung von TIOCSTOP auf.
  214.  
  215.  
  216. Erfragen/Setzen der Puffereinstellungen
  217. ---------------------------------------
  218. #define TIOCBUFFER (('T'<<8) | 128)
  219. special zeigt beim Aufruf auf eine Struktur:
  220. LONG   Gr”že des Eingabepuffers in Byte
  221. LONG   untere Wassermarke des Eingabepuffers in Byte
  222. LONG   obere Wassermarke des Eingabepuffers in Byte
  223. LONG   Gr”že des Ausgabepuffers in Byte
  224. Soll ein Wert nur erfragt bzw. nicht ge„ndert werden, so ist anstelle des 
  225. Wertes eine -1 anzugeben. Wird anstelle eines Wertes -1 zurckgegeben, so 
  226. wird diese Funktion nicht untersttzt. Werden Werte gesetzt, so sollte man 
  227. auch den Rckgabewert prfen, da der Treiber bei ihm nicht passenden 
  228. Vorgaben die n„chstliegenden ihm passenden Werte einsetzt und benutzt. 
  229. (Hinweis: Es ist allein Sache des Treibers, den Speicher irgendwo zu 
  230. reservieren oder freizugeben. Das kann man auch unter TOS programmieren.)
  231.  
  232.  
  233. Erfragen der I/O-Leitungen und Signalisierungsf„higkeiten
  234. ---------------------------------------------------------
  235. #define TIOCCTLMAP (('T'<<8) | 129)
  236. special ist Zeiger auf eine Struktur aus 6 LONGs, die durch den Treiber 
  237. ausgefllt wird. In jedem LONG wird fr jede vorhandene 
  238. Steuer/Melde-Leitung oder F„higkeit das Bit auf 1 gesetzt.
  239. 1.LONG: Leitung ber TIOCCTL(GET/SET) abfrag/beeinflužbar
  240. 2.LONG: Reaktion (Routinenaufruf) bei Eintreten des Zustandes m”glich.
  241. 3.LONG: Reaktion (Routinenaufruf) bei Beendigung des Zustandes m”glich.
  242. 4.LONG: reserviert fr zuknftige Erweiterungen, bis dahin 0
  243. 5.LONG: reserviert fr zuknftige Erweiterungen, bis dahin 0
  244. 6.LONG: reserviert fr zuknftige Erweiterungen, bis dahin 0
  245. Die Zuordnung der Bits zu den "Leitungen" lautet:
  246. #define TIOCM_LE   0x0001 /* line enable output, Ausgang */
  247. #define TIOCM_DTR  0x0002 /* data terminal ready, Ausgang */
  248. #define TIOCM_RTS  0x0004 /* ready to send, hat heute andere Bedeutung,
  249. Ausgang */
  250. #define TIOCM_CTS  0x0008 /* clear to send, hat heute andere Bedeutung,
  251. Eingang */
  252. #define TIOCM_CAR  0x0010 /* data carrier detect, Eingang */
  253. #define TIOCM_CD   TIOCM_CAR /* alternativer Name */
  254. #define TIOCM_RNG  0x0020 /* ring indicator, Eingang */
  255. #define TIOCM_RI   TIOCM_RNG /* alternativer Name */
  256. #define TIOCM_DSR  0x0040 /* data set ready, Eingang */
  257. #define TIOCM_LEI  0x0080 /* line enable input, Eingang */
  258. #define TIOCM_TXD  0x0100 /* Sendedatenleitung, Ausgang */
  259. #define TIOCM_RXD  0x0200 /* Empfangsdatenleitung, Eingang */
  260. #define TIOCM_BRK  0x0400 /* Break erkannt, Pseudo-Eingang */
  261. #define TIOCM_TER  0x0800 /* Sendefehler, Pseudo-Eingang */
  262. #define TIOCM_RER  0x1000 /* Empfangsfehler, Pseudo-Eingang */
  263. #define TIOCM_TBE  0x2000 /* Hardware-Sendepuffer leer, Pseudo-Eingang */
  264. #define TIOCM_RBF  0x4000 /* Hardware-Empfangspuffer voll, Pseudo-Eingang */
  265.  
  266. Nichtdefinierte Bits sollten ignoriert werden.
  267.  
  268. Das Nichtvorhandensein einer Leitung im TIOCCTLMAP bedeutet nur, daž diese 
  269. Leitung nicht per TIOCCTLxxx abfragbar/steuerbar ist. Es bedeutet nicht, 
  270. daž diese Leitung hardwarem„žig nicht existiert. Es ist m”glich, daž eine 
  271. Leitung mit Callback-Routinen berwachbar ist, aber nicht mit TIOCCTLGET 
  272. abgefragt werden kann.
  273.  
  274. Einige TIOCM_* haben Besonderheiten, die hier erkl„rt werden:
  275.  
  276. TIOCM_TER, TIOCM_RER
  277. Der Routine wird in D0.b ein Byte bergeben, das den Fehler genauer angibt:
  278. Byte Fehler
  279. 0    allgemeiner, nicht genauer spezifizierbarer Fehler
  280. 1    Hardware-Empfangspufferberlauf
  281. 2    Software-Empfangspufferberlauf
  282. 3    Parit„tsfehler
  283. 4    Rahmenfehler
  284.  
  285. Abfrage von TIOCM_BRK, TIOCM_RER und TIOCM_TER mit TIOCCTLGET: Ein 
  286. auftretender "Fehler" setzt das Statusbit. Eine allgemeine (-1) oder 
  287. spezielle Abfrage (auf BRK, RER, TER) liefert den Zustand des 
  288. entsprechenden Statusbits und setzt es gleichzeitig zurck.
  289.  
  290. TIOCM_TBE
  291. Der Routine wird in D0.w -1 bergeben, falls im Software-Sendepuffer kein 
  292. Byte mehr ist. Andernfalls wird ein Byte aus dem Software-Sendepuffer 
  293. gelesen und in D0.b bergeben, D0.bit15 ist dann =0. Die Routine gibt in 
  294. D0.w -1 zurck, falls nichts gesendet werden soll. Sie gibt D0.bit15 =0 und 
  295. in D0.b das Byte zurck, falls es gesendet werden soll. Diese Routine wird 
  296. ebenfalls aufgerufen, wenn ein Byte neu in den Software-Sendepuffer 
  297. geschrieben wurde, und der Sendepuffer schon lange leer ist. Gibt diese 
  298. Routine ein selbst erzeugtes -1 zurck und stehen noch Daten im 
  299. Software-Sendepuffer, so wird sie sp„testens nach einer Sekunde erneut 
  300. aufgerufen.
  301.  
  302. TIOCM_RBF
  303. Der Routine wird in D0.b das empfangene Byte bergeben. Sie gibt in D0.w -1 
  304. zurck, falls nichts in den Software-Empfangspuffer geschrieben werden 
  305. soll. Andernfalls gibt sie D0.bit15 =0 und in D0.b das Byte zurck, das in 
  306. den Software-Empfangspuffer geschrieben werden soll.
  307.  
  308.  
  309. Abfragen der I/O-Leitungen und Signalisierungen
  310. -----------------------------------------------
  311. #define TIOCCTLGET (('T'<<8) | 130)
  312. liefert auf der durch special angegebenen Speicherstelle ein LONG, in dem 
  313. die aktuellen Zust„nde der CTLleitungen abgelegt werden, Kodierung wie bei 
  314. TIOCCTLMAP. Auf special wird auch ein Parameter hin bergeben: Ist er -1, 
  315. so werden alle CTLleitungen erfragt, ist er <>-1, so darf nur ein Bit 
  316. gesetzt sein, und es wird nur diese CTLleitung erfragt. Der Treiber darf 
  317. trotzdem auch die Werte der anderen Leitungen zu liefern. Das geschieht aus 
  318. Geschwindigkeitsgrnden. Unsinnig gesetzte Bits werden ignoriert.
  319.  
  320.  
  321. Setzen der I/O-Leitungen und Signalisierungen
  322. -----------------------------------------------
  323. #define TIOCCTLSET (('T'<<8) | 131)
  324. special zeigt auf eine Struktur:
  325. LONG ctlmaske
  326. LONG ctlvalues
  327. Es werden die in ctlmaske gesetzten Bit (Kodierung wie bei TIOCCTLMAP) auf 
  328. die in ctlvalues vorhandenen Werte gesetzt. In ctlmaske darf man natrlich 
  329. nur Bits setzen, deren Funktion man kennt. Eingabeleitungen lassen sich 
  330. nicht beeinflussen, solche Setzversuche werden wie unsinnige Bits 
  331. ignoriert.
  332.  
  333.  
  334. Konzept der Callback-Funktionen
  335. -------------------------------
  336. Ein Programm kann Funktionen anmelden, die beim Eintreten bestimmter 
  337. Zust„nde sehr schnell aufgerufen werden. Angemeldet wird die Funktion durch 
  338. šbergabe ihrer Adresse in procadr. Dabei ist Bit0 immer 0. Abgemeldet wird 
  339. durch den gleichen Aufruf, aber mit gesetzem Bit0 (also =1) in procadr, 
  340. also einer ungeraden Adresse! Bit31-1 mssen genau wie ctlline den gleichen 
  341. Wert wie beim Installieren aufweisen. Wenn bei den einzelnen Funktionen 
  342. nichts anderes steht, gelten folgende Grunds„tze:
  343. - Nur Register D0 und A0 drfen ver„ndert werden.
  344. - Sie muá extrem kurz sein, mehr als 20 "normale" Assemblerbefehle sind
  345.   unzul„ssig (ein MOVEM.L D1-D7/A1-A6,... oder DIV ist nicht als "normal"). 
  346.   Anders ausgedrckt: die Laufzeit der Routine sollte auf einer CPU MC68000 
  347.   200 Takte nicht berschreiten.
  348. - Aufruf erfolgt im Supervisormode.
  349. - Der aktuelle InterruptPriorityLevel ist unbestimmt.
  350. - Ende mit RTS.
  351.  
  352. Es ist denkbar, daá mehrere Programme gleichzeitig eine Leitung berwachen. 
  353. Man muá die Routine abmelden, bevor sie durch eine nichtresidente 
  354. Beendigung des Programms aus dem Speicher fliegt. Es ist egal, welcher 
  355. Filehandle zur An-/Abmeldung benutzt wird, wenn er auf das entsprechende 
  356. Device pažt (z.B. Fopen, Fcntl(...,TIOCCTLSFAST) /*Anmeldung*/, Fclose, 
  357. ... Fopen, Fcntl(...,TIOCCTLSFAST) /*Abmeldung*/, Fclose).
  358.  
  359. Manche Funktionen werden nur bei bestimmten Handshakemodi existieren und 
  360. k”nnen nur unter diesen Modi angemeldet, aber unter jedem Modus abgemeldet 
  361. werden. Sie werden beim Umschalten des Handshakes automatisch aktiviert und 
  362. deaktiviert, solange sie angemeldet sind.
  363.  
  364.  
  365. Anmelden/Abmelden schneller Callback-Funktionen
  366. -----------------------------------------------
  367. #define TIOCCTLSFAST (('T'<<8) | 132)
  368. Anmelden und Abmelden von Routinen, die bei Status„nderung der CTLleitungen
  369. aufgerufen werden. special ist ein Zeiger auf Struktur:
  370. LONG ctlline
  371. LONG procadr
  372. Die Routine wird m”glichst (siehe dazu TIOCCTLMAP) bei jeder Flanke auf der 
  373. in ctlline (dort darf nur ein Bit gesetzt sein, siehe TIOCCTLMAP) 
  374. angegebenen Leitung aufgerufen. Der dabei angenommene neue Pegel der 
  375. Leitung wird in D0.b bergeben: 0 inaktiv (bei DSR w„re es TTL-High-Pegel) 
  376. und $FF fr aktiv.
  377. Returnwerte der Funktion:
  378. E_OK    alles OK
  379. 1       Routine installiert, aber sie ist nicht die einzige. So langsam wird
  380.         es zeitkritisch, das Programm sollte wenn m”glich die Routine wieder
  381.         deinstallieren. (Das ist nur eine Empfehlung)
  382. EINVFN  diese šberwachungsm”glichkeit gibt es nicht
  383. EACCDN  Routine kann nicht mehr installiert werden.
  384.  
  385.  
  386. Anmelden/Abmelden langsamer Callback-Funktionen
  387. -----------------------------------------------
  388. #define TIOCCTLSSLOW (('T'<<8) | 133)
  389. fast identisch zu CTLSIGFAST, mit einem Unterschied: Die Routine darf fast 
  390. beliebig lang sein.
  391.  
  392.  
  393. Erfragen der Anzahl noch nicht gesendeter Byte
  394. ----------------------------------------------
  395. #define TIONOTSEND (('T'<<8) | 134)
  396. Fcntl( handle, &count, TIONOTSEND)
  397. In count wird als 32Bit-Wert die Anzahl der Byte hinterlassen, die noch 
  398. nicht gesendet wurden. Es wird versucht, im Rahmen der M”glichkeiten 
  399. (Hardware-FIFOs), m”glichst genau zu bestimmen, wieviel nichtgesendete 
  400. Zeichen im Rechner sind.
  401.  
  402.  
  403. Einstellung des Verhaltens bei Fehlern
  404. --------------------------------------
  405. #define TIOCERROR (('T'<<8) | 135)
  406. Fcntl( handle, &errmode, TIOCERROR);
  407. errmode ist ein LONG. Ist errmode -1, wird in errmode nur die aktuelle 
  408. Einstellung geliefert. Ist errmode >=0, so werden die Einstellungen gesetzt 
  409. und die vorigen Werte geliefert. In Bit7..0 von errmode wird ein Zeichen 
  410. bergeben. Bit8 =1 schaltet das Einfgen dieses Zeichens in den 
  411. Empfangspuffer bei einem Empfangsfehler ein. Normalerweise ist Bit8 =0, bei 
  412. einem Fehler wird kein Zeichen in den Puffer geschrieben. Bit9 =1 schaltet 
  413. das L”schen des Empfangspuffers bei Empfang von Break ein, normalerweise 
  414. ist Bit9 =0 und es erfolgt keine Pufferl”schung bei Break. Rckgabewert ist 
  415. E_OK, bei nicht untersttzten Einstellungen ERANGE.
  416.  
  417.  
  418. --- Ende des Textes ---
  419.  
  420.  
  421.  
  422.  
  423. Definition of a software interface, providing a fully hardware
  424. independend use of serial interfaces
  425. ==============================================================
  426.  
  427. written by: Harun Scheutzow, Dresdener Straže 83, D-10179 Berlin
  428. Internet-Email: Harun_Scheutzow@B.maus.de
  429. last change of definition: 12.Nov.1993
  430. last change of explaination: 24.Oct.1994
  431.  
  432. It should be defined (if possible) all functions, a terminal program, a 
  433. transfer protocol such as ZMODEM or eg. a fax program will need. This 
  434. functions realize a hardware independent interface for programs.
  435.  
  436. This proposal is known to Eric Smith. He wrote to me last:
  437. "Note that I can't say that this will be an 'official' Atari standard 
  438. right now; we haven't had time to review it completely and make it 
  439. official. But it seems OK to me, and it's better to have an 
  440. unofficial standard than no standard at all, I think."
  441. (Only the callbacks he likes not so much, because of possible problems 
  442. with memory protection).
  443.  
  444. MiNT or TOS or a loaded driver should support as much as possible of the 
  445. functions described here, if the hardware allows it. But every software has 
  446. to consider, that a function could not exist and only return the error 
  447. EINVFN (-32). If the absence of a function prevents the proper work of the 
  448. software, the user must be informed about this fact by this software.
  449.  
  450. This is a attemp to standardize the interface found by user programms. 
  451. About the interna of driver implementation nothing should be written. All 
  452. functions and suggestions should be implementable on an 68000 with 8MHz and 
  453. 38400Bd transfer by the MFP (68901, without hardware-FIFO). The rising 
  454. performance of the CPUs is no argument, because the demanded data transfer 
  455. rate rises permanently too.
  456.  
  457.  
  458. Everybody should know Fopen, Fread, Fwrite, Fclose as normal 
  459. GEMDOS-functions. Fcntl is the GEMDOS-function $104, with LONG Fcntl( WORD 
  460. filehandle, LONG special, WORD subfunction), existing in MiNT (and in 
  461. HSMODEM). Fcntl returns mostly a 0 as OK-message, or otherwise a error 
  462. code. Any requested values are used to return in a memory cell the 
  463. parameter special is pointing to, and not as return code of Fcntl.
  464.  
  465. Reserving of an interface I like to realize about the opening mode of Fopen.
  466.  
  467.  
  468.  
  469. The description of the following functions is a modified copy from same 
  470. files included in a MiNT distribution.
  471.  
  472.  
  473. Some lines are C, some comment. The function calls are really examples and 
  474. not prototypes.
  475.  
  476.  
  477. How many bytes may be transfered nonblocking?
  478. ---------------------------------------------
  479. #define FIONREAD  (('F'<< 8) | 1)
  480. #define FIONWRITE (('F'<< 8) | 2)
  481. Fcntl( handle, &count, FIONREAD)
  482. Fcntl( handle, &count, FIONWRITE)
  483. count is a 32Bit-value in which the function returns the number of bytes, 
  484. which can be at least read / written during the next Fread/Fwrite. Because 
  485. more than one program could write to a interface, nobody should rely on 
  486. this. Only Fread/Fwrite return, how much byte are really transfered.
  487.  
  488.  
  489. Set and Reset Break
  490. -------------------
  491. #define TIOCCBRK (('T'<< 8) | 20)
  492. #define TIOCSBRK (('T'<< 8) | 21)
  493. Fcntl( handle, dummy, TIOCSBRK); /* aktivate Break */
  494. Fcntl( handle, dummy, TIOCCBRK); /* clear Break */
  495.  
  496.  
  497. Set/Inquire the input speed and DTR-line control
  498. ------------------------------------------------
  499. #define TIOCIBAUD (('T'<< 8) | 18)
  500. Fcntl( handle, &speed, TIOCIBAUD);
  501. Set the input speed of the interface. speed is a 32Bit-value, which 
  502. contains the requested speed uncoded in bits per second. speed = 19200 
  503. would set the speed to 19200bps. The old (real) input speed is returned in 
  504. speed. If the old speed is unknown, -1 is returned. If speed = -1 as input 
  505. parameter of TIOCIBAUD, only the input speed is returned. If speed = 0, the 
  506. DTR-line will be inaktivated (cleared, dropped), without influence on the 
  507. real speed. Every TIOCIBAUD-call which sets the speed, aktivates 
  508. automatically DTR. Returnvalue is ERANGE if the requested speed is not 
  509. available. In this case (as exception) the next lowest legal speed is 
  510. returned in speed. If a next lowest speed is unavailable too, the lowest 
  511. legal speed is returned.
  512.  
  513.  
  514. Set/Inquire the output speed and DTR-line control
  515. -------------------------------------------------
  516. #define TIOCOBAUD (('T'<< 8) | 19)
  517. Fcntl( handle, &speed, TIOCOBAUD);
  518. Set output speed of the interface. The function description is identical 
  519. with TIOCIBAUD. If a device does not support different input and output 
  520. speed, TIOCIBAUD and TIOCOBAUD affects both speeds.
  521.  
  522.  
  523. Inquire protocol settings
  524. -------------------------
  525. #define TIOCGFLAGS (('T'<< 8) | 22)
  526. Fcntl( handle, &flags, TIOCGFLAGS);
  527. Get the terminal control flags bits. 16 bit flag word flags is set to 
  528. reflect the current terminal state. It is a OR-connection of bits and bit 
  529. combinations. Not defined bits should be ignored. A program should read 
  530. the flags with TIOCGFLAGS, modify the interesting, and set the new value 
  531. with TIOCSFLAGS.
  532.  
  533. /* Number of stopbits */
  534. #define TF_STOPBITS 0x0003
  535. /* 0x0000  illegal
  536. extension proposal: This aktives the synchron mode. The remaining bits will 
  537. have other meanings in synchron mode, which must be defined in future. */
  538. #define TF_1STOP   0x0001 /* 1 Stopbit */
  539. #define TF_15STOP  0x0002 /* 1.5 Stopbit */
  540. #define    TF_2STOP   0x0003 /* 2 Stopbit */
  541.  
  542. /* Bits per character */
  543. #define TF_CHARBITS 0x000C
  544. #define TF_8BIT    0x0 /* 8 Bit */
  545. #define TF_7BIT    0x4
  546. #define TF_6BIT    0x8
  547. #define TF_5BIT    0xC /* 5 Bit */
  548.  
  549. /* Handshake and parity */
  550. #define TF_FLAG  0xF000
  551. #define T_TANDEM 0x1000 /* XON/XOFF (=^Q/^S) flow control aktiv */
  552. #define T_RTSCTS 0x2000 /* RTS/CTS flow control aktiv */
  553. #define T_EVENP  0x4000 /* even parity aktiv */
  554. #define T_ODDP   0x8000 /* odd parity aktiv */
  555. /* even and odd are mutually exclusive */
  556.  
  557.  
  558. Set protocol settings
  559. ---------------------
  560. #define TIOCSFLAGS (('T'<< 8) | 23)
  561. Fcntl( handle, &flags, TIOCSFLAGS);
  562. Set the settings, description see TIOCGFLAGS. Returnvalue is ERANGE if a 
  563. illegal or not support combination occurs in flags.
  564.  
  565.  
  566. End of documentation of existing MiNT functions. New proposals follow:
  567.  
  568.  
  569. Flush serial buffers
  570. --------------------
  571. #define TIOCFLUSH (('T'<< 8) | 8)
  572. Fcntl( handle, special, TIOCFLUSH);
  573. (in MiNT "/* BUG: this should flush the input/output buffers */")
  574. Selected by the special-parameter the buffers are flushed in different 
  575. ways:
  576. special  function
  577. 0
  578.          Send the transmit buffer. The function returns, if the transmit 
  579.          buffer is empty (return E_OK, =0) or if a internal timeout occurs 
  580.          (return EDRVNR, =-2). The system takes a reasonable timeout.
  581. 1
  582.          Clear the receive buffer.
  583. 2
  584.          Clear the transmit buffer.
  585. 3
  586.          Clear receive and transmit buffer.
  587. -tout
  588.          A negative parameter works as 0, but tout (hint: tout is positive) 
  589.          gives the timeout in 1/200 seconds.
  590.  
  591.  
  592. Stop receive
  593. ------------
  594. #define TIOCSTOP (('T'<< 8) | 9)
  595. is only available in the handshake modi and signals the communication 
  596. partner, that the computer wants to receive nothing. The function waits a 
  597. reasonable time for collecting characters already in transmission. Then it 
  598. returns, thinking, the partner stopped transmission. (Example for use: an 
  599. 8MHz-ST is unable to do simultaneously DMA and 57600Bd-receive by MFP.)
  600.  
  601.  
  602. Start receive
  603. -------------
  604. #define TIOCSTART (('T'<< 8) | 10)
  605. Eliminates effects of TIOCSTOP.
  606.  
  607.  
  608. Inquire/Set buffer settings
  609. ---------------------------
  610. #define TIOCBUFFER (('T'<<8) | 128)
  611. special points to a structure:
  612. LONG   input buffer size in byte
  613. LONG   low water mark in byte
  614. LONG   high water mark in byte
  615. LONG   output buffer size in byte
  616. If a value should inquired only, use a -1 instead of the value. Is a -1 
  617. returned instead of a value, this function is not supported. If values are 
  618. set, the returned values should be examined, because the driver may use not 
  619. the given ones, but the next values the driver founds suitable. (Hint: The 
  620. driver has to allocate an free the memory. That is implementable under 
  621. plain TOS too.)
  622.  
  623.  
  624. Inquire I/O-lines and signaling capabilities
  625. --------------------------------------------
  626. #define TIOCCTLMAP (('T'<<8) | 129)
  627. special is a pointer to a structur of 6 LONGs which is filled out by the 
  628. driver. In every LONG the corresponding bit is set to 1 for a existing 
  629. control line or capability.
  630. 1.LONG: line inquire-/setable with TIOCCTL(GET/SET)
  631. 2.LONG: aktion (routine call) possible at start of condition
  632. 3.LONG: aktion (routine call) possible at end of condition
  633. 4.LONG: reserved for future extension, till then 0
  634. 5.LONG: reserved for future extension, till then 0
  635. 6.LONG: reserved for future extension, till then 0
  636. corresponding bits and "lines":
  637. #define TIOCM_LE   0x0001 /* line enable output, output */
  638. #define TIOCM_DTR  0x0002 /* data terminal ready, output */
  639. #define TIOCM_RTS  0x0004 /* ready to send, today other meaning, output */
  640. #define TIOCM_CTS  0x0008 /* clear to send, today other meaning, input */
  641. #define TIOCM_CAR  0x0010 /* data carrier detect, input */
  642. #define TIOCM_CD   TIOCM_CAR /* alternative name */
  643. #define TIOCM_RNG  0x0020 /* ring indicator, input */
  644. #define TIOCM_RI   TIOCM_RNG /* alternative name */
  645. #define TIOCM_DSR  0x0040 /* data set ready, input */
  646. #define TIOCM_LEI  0x0080 /* line enable input, input */
  647. #define TIOCM_TXD  0x0100 /* transmit data line, output */
  648. #define TIOCM_RXD  0x0200 /* receive data line, input */
  649. #define TIOCM_BRK  0x0400 /* Break detected, pseudo-input */
  650. #define TIOCM_TER  0x0800 /* transmit error, pseudo-input */
  651. #define TIOCM_RER  0x1000 /* receive error, pseudo-input */
  652. #define TIOCM_TBE  0x2000 /* hardware-transmitter buffer empty, 
  653. pseudo-input */
  654. #define TIOCM_RBF  0x4000 /* hardware-receiver buffer full, pseudo-input */
  655.  
  656. Undefined bits should be ignored.
  657.  
  658. The absence of a line in TIOCCTLMAP means only, that this line is not 
  659. accessible by TIOCCTLxxx. It does not mean, that this line does not exist 
  660. in the hardware. It is possible, that a line can only be by monitored by 
  661. callbacks, but not by TIOCCTLGET.
  662.  
  663. Some TIOCM_* have special features, described here:
  664.  
  665. TIOCM_TER, TIOCM_RER
  666. The routine gets in D0.b a byte, describing the error in detail:
  667. Byte Error
  668. 0    no more information available about this error
  669. 1    hardware-receiver buffer overflow
  670. 2    software-receiver buffer overflow
  671. 3    parity error
  672. 4    framing error
  673.  
  674. Requesting TIOCM_BRK, TIOCM_RER or TIOCM_TER via TIOCCTLGET: If the 
  675. condition occurs, the corresponding status bit ist set. A common (-1) or 
  676. dedicated (BRK, RER or TER) request returns the state of the corresponding 
  677. bit and resets it.
  678.  
  679. TIOCM_TBE
  680. The routine gets in D0.w -1, if the software-transmit buffer is empty. 
  681. Otherways it gets a byte read out from the software-transmit buffer in 
  682. D0.b, D0.bit15 is =0 in this case. The routine returns in D0.w -1, if 
  683. nothing should be sent. It returns D0.bit15 =0 and in D0.b the byte, if the 
  684. byte should be sent. The routine is called too, if a new byte is written 
  685. into the software-transmit buffer and the buffer was empty before. If the 
  686. routine returns a self generated -1 and there are bytes available in the 
  687. software-transmit buffer, the routine is called again latest after one 
  688. second.
  689.  
  690. TIOCM_RBF
  691. The routine gets in D0.b the received byte. The routine returns in D0.w -1, 
  692. if nothing should be written into the software-receive buffer. Otherwise it 
  693. returns D0.bit15 =0 and in D0.b the Byte zurck, which should be written 
  694. into the software-receive buffer.
  695.  
  696.  
  697. Inquire I/O-lines and signals
  698. -----------------------------
  699. #define TIOCCTLGET (('T'<<8) | 130)
  700. returns a LONG in the memory cell special points to, which contains the 
  701. actual conditions of the CTLlines, coding see TIOCCTLMAP. On special is 
  702. given a parameter to this function too: If -1, all CTLlines are inquired, 
  703. if <>-1, only one bit has to be set, and only this CTLline is inquired. The 
  704. driver may provide never the less the values of the other lines, because of 
  705. speed reasons. Senseless set bits are ignored.
  706.  
  707.  
  708. Set I/O-lines and signals
  709. -------------------------
  710. #define TIOCCTLSET (('T'<<8) | 131)
  711. special points to a structur:
  712. LONG ctlmaske
  713. LONG ctlvalues
  714. The bits which are set in ctlmaske (coding see TIOCCTLMAP), are set to the 
  715. values in ctlvalues. A software should only set bit(s) in ctlmaske, if it 
  716. knows its functions. Input lines are unchangable, such bits are ignored as 
  717. senseless bits.
  718.  
  719.  
  720. concept of callback-functions
  721. -----------------------------
  722. A programm can install functions, which are called nearly immediately if a 
  723. condition occurs. A function becomes installed by giving its address in 
  724. procadr. During this installation Bit0 is always 0. A function becomes 
  725. uninstalled by the same call, but with set bit0 (=1) in procadr, with a odd 
  726. address! Bit31-1 and ctlline must have the same value as during 
  727. installation. If there are no special remarks for outstanding functions, 
  728. the following basic rules apply:
  729. - Only register D0 and A0 may be changed.
  730. - It must be extremly short, more than 20 "normal" assembler instructions
  731.   are not allowed (a MOVEM.L D1-D7/A1-A6,... or DIV is not "normal"). The 
  732.   rum time of the routine should not exceed 200 clocks on a CPU MC68000.
  733. - Call is made in supervisormode.
  734. - The actual InterruptPriorityLevel is unknown.
  735. - End with RTS.
  736.  
  737. It is possible, that several programs watch one line simultaneously. The 
  738. routine must be uninstalled, before it leaves the memory because a non 
  739. resident program termination. It is unimportant, which file handle is used 
  740. for (un-/)registration, if it matches the device (e.g. Fopen, 
  741. Fcntl(...,TIOCCTLSFAST) /*installation*/, Fclose, ... Fopen, 
  742. Fcntl(...,TIOCCTLSFAST) /*uninstallation*/, Fclose).
  743.  
  744. Some functions exist only under special handshake modi and can only 
  745. installed if this mode is activ, but uninstalled under every mode. Such 
  746. functions are automatically activated and deaktivated, as long as they are 
  747. installed.
  748.  
  749.  
  750. Install/Uninstall fast callback-functions
  751. -----------------------------------------
  752. #define TIOCCTLSFAST (('T'<<8) | 132)
  753. Installation and uninstallation of routines, which are called if changes on 
  754. the CTLlines occur. special is a pointer to a structur:
  755. LONG ctlline
  756. LONG procadr
  757. The routine is called on every transition (if possible, see TIOCCTLMAP) on 
  758. the line marked in ctlline (only one bit should be set, see TIOCCTLMAP). 
  759. The new level of the line is given in D0.b: 0 inaktiv (on the DSR line 
  760. inaktiv means TTL-high-level, for example) and $FF aktiv.
  761. Returnvalues of TIOCCTLSFAST:
  762. E_OK    everything OK
  763. 1       routine installed, but it is not the only one. It becomes time
  764.         critic, if possible, the programm should uninstall the routine. 
  765.         This is only a recommendation.
  766. EINVFN  this watch capability does not exist
  767. EACCDN  routine can not be installed.
  768.  
  769.  
  770. Install/Uninstall slow callback-functions
  771. -----------------------------------------
  772. #define TIOCCTLSSLOW (('T'<<8) | 133)
  773. nearly identical to TIOCCTLSFAST, with one difference: The routine may be 
  774. (nearly) as long as it likes to be.
  775.  
  776.  
  777. Inquire number of unsent bytes
  778. ------------------------------
  779. #define TIONOTSEND (('T'<<8) | 134)
  780. Fcntl( handle, &count, TIONOTSEND)
  781. The function returns in count as a 32bit-value the number of bytes, which 
  782. are not sent at this moment. The function tries, limited by the hardware 
  783. (hardware-FIFOs), exactly to find out how much unsent characters in the 
  784. computer are.
  785.  
  786.  
  787. Set error behavior
  788. ------------------
  789. #define TIOCERROR (('T'<<8) | 135)
  790. Fcntl( handle, &errmode, TIOCERROR);
  791. Errmode is a 32bit value. If errmode is -1 as input parameter, in errmode 
  792. is only the actual setting returned. If errmode >=0, the error behavior 
  793. will be set and the old setting is returned in errmode. In Bit7..0 of 
  794. errmode is a character. Bit8 =1 switchs on the insert of this character 
  795. into the receive buffer if a receive error occurs. Normally is Bit8 =0, and 
  796. no character is inserted during a error. Bit9 =1 switchs on the clearance 
  797. of receive buffer if break is received, normally is Bit9 =0 and the buffer 
  798. is not influenced by break. Returnvalue is E_OK, or ERANGE for not 
  799. supported settings.
  800.  
  801.  
  802. --- end of text ---
  803.